home *** CD-ROM | disk | FTP | other *** search
/ Internet Tools (InfoMagic) / Internet Tools.iso / applic / ncsa / tn3270 / binhex.helpcms.Z / binhex.helpcms
Text File  |  1989-11-18  |  11KB  |  225 lines
  1. .fo off
  2. .cs 1 on
  3.  
  4. BINHEX
  5.  
  6. Use the  BINHEX command  to work  with Macintosh  files containing  binary data
  7. which are stored  in CMS.   BINHEX may be  used with HQX files,   such as those
  8. created by BinHex 4.0 on the Macintosh, and also with BIN files,  such as those
  9. created by BinHex  5.0.   BINHEX checks files in these  formats,  describes the
  10. contents of the files, and converts between the two formats.
  11. .cs 1 off
  12. .cs 2 on
  13. The format of the BINHEX command is:
  14.  
  15. ┌──────────╛──────────────────────────────────────────────────────────────────┐
  16. │          │                                                                  │
  17. │ BINHEX   │ ? | Check | Describe | COnvert  fn <ft <fm >>   [(options...[)]] │
  18. │          │                                                                  │
  19. │          │ Options:                                                         │
  20. │          │     ┌           ┐  ┌           ┐  ┌           ┐                  │
  21. │          │     │To fm      │  │Stack      │  │Fifo       │                  │
  22. │          │     │Rate cps   │  │Lifo       │  │STEm stm   │                  │
  23. │          │     └           ┘  └           ┘  └           ┘                  │
  24. │          │                                                                  │
  25. └──────────╩──────────────────────────────────────────────────────────────────┘
  26. .cs 2 off
  27. .cs 3 on
  28.  
  29. OPERANDS
  30.  
  31. ?         causes BINHEX  to type  a brief  description of  the command  format,
  32.           including all the valid operands and options.  When "?" is specified,
  33.           the remainder of the command line is ignored.
  34.  
  35. Check     cause BINHEX to check the input file  for errors,  such as missing or
  36.           corrupted data.   BINHEX will either report  there are no errors,  or
  37.           respond with an  error message describing the  problem.   BINHEX also
  38.           checks  the  input file  when  the  Describe  or COnvert  operand  is
  39.           specified.
  40.  
  41. Describe  causes BINHEX to display information about the input file,  including
  42.           the full Macintosh filename, the type, creator, flags values, and the
  43.           sizes of the  data and resource forks.   See  the "Responses" section
  44.           below for examples of the information which is displayed.
  45.  
  46. COnvert   causes BINHEX  to convert  the input  file from  BinHex to  MacBinary
  47.           format or vice-versa.    The resulting file has the  same filename as
  48.           the input file,  and a filetype  of either BIN (for MacBinary format)
  49.           or HQX (for BinHex format).   The file is written to the same disk as
  50.           the input file, unless the "To" option has been specified.
  51.  
  52. fn        specifies the filename of the input file.
  53.  
  54. ft        specifies the filetype  of the input file.   When "ft"  is omitted or
  55.           specified as "*",  all filetypes will be searched to find a match for
  56.           "fn".
  57.  
  58. fm        specifies the filemode  of the input file.   When "fm"  is omitted or
  59.           specified as  "*",  all accessed  disks will  be searched for  a file
  60.           matching "fn" and "ft".
  61.  
  62. OPTIONS
  63.  
  64. To fm     specifies the disk to which the output  file will be written when the
  65.           "COnvert" operand is  specified.   When "To" is  omitted,  the output
  66.           file is written to the same disk as the input file.
  67.  
  68. Rate cps  specifies a file transfer rate in characters per second.  When a rate
  69.           is specified,  the  information displayed by the  "Describe" function
  70.           will include an estimate of the time required to download the file.
  71.  
  72. Stack     cause the output  from the "Describe" function to be  stacked in FIFO
  73.           order.  "Fifo" is a synonym for "Stack".
  74.  
  75. Lifo      causes the output from the "Describe"  function to be stacked in LIFO
  76.           order.
  77.  
  78. Fifo      cause the output  from the "Describe" function to be  stacked in FIFO
  79.           order.  "Stack" is a synonym for "Fifo".
  80.  
  81. STEm stm  causes the output from the "Describe"  function to be stored directly
  82.           into REXX  or EXEC2 variables.    "stm" is the  name of the  stem for
  83.           these variables,   i.e.  the characters  preceding a period  in their
  84.           names.   Only  the first eight  characters of "stm"  are significant.
  85.           The following variables are defined:
  86.  
  87.                stm.FN         CMS filename
  88.                stm.FT         CMS filetype
  89.                stm.FM         CMS filemode
  90.                stm.FORMAT     BinHex or MacBinary
  91.                stm.NAME       Mac filename
  92.                stm.TYPE       Mac type
  93.                stm.CREATOR    Mac creator
  94.                stm.FLAGS      Mac flags
  95.                stm.DATASIZE   Mac data fork size
  96.                stm.RESCSIZE   Mac resource fork size
  97.                stm.CRDATE     Mac creation date
  98.                stm.MDDATE     Mac last modified date
  99.                stm.CHARCNT    Total character count
  100.                stm.TIMEEST    Download time estimate
  101.  
  102.           The  creation and  last modified  dates  are not  defined for  BinHex
  103.           format files,   which do  not include  them.   The  time estimate  is
  104.           defined only when the Rate option has been specified.
  105.  
  106. USING THE BINHEX COMMAND
  107.  
  108. The BINHEX  command allows  Macintosh users to  obtain information  about files
  109. stored in CMS which would ordinarily not  be available until the files had been
  110. downloaded to a  Macintosh.   The Check function  verifies that a file  will be
  111. accepted  by BinHex  on  the Macintosh,   and  the  Describe function  provides
  112. detailed information about a file.  With this information, a Macintosh user can
  113. often avoid  spending time  downloading unwanted files  or files  which contain
  114. errors.   The COnvert function provides conversion between the two file formats
  115. BINHEX accepts:   BinHex format  and MacBinary  format.   Conversion  is useful
  116. because each of these formats offers advantages for storing Macintosh programs.
  117.  
  118. BinHex format is used by BinHex 4.0 on the Macintosh.  It consists of a header,
  119. the data  fork,  and  the resource fork  of a  Macintosh file,   compressed and
  120. converted to printable characters.   Converting a file from binary to printable
  121. characters increases its size (in spite  of the inclusion of file compression).
  122. However,  since  they contain only printable  characters,  BinHex files  can be
  123. included in electronic mail,  and can be  uploaded and downloaded in nearly any
  124. environment.   In  CMS,  BinHex  files usually  are given  filetypes containing
  125. "HQX", and may have fixed or variable-length records.   The files usually begin
  126. with the line
  127.  
  128.      (This file must be converted with BinHex 4.0)
  129.  
  130. MacBinary format is used by BinHex 5.0 and MacTerminal on the Macintosh.  It is
  131. similar to BinHex format,  but retains the file contents in binary form instead
  132. of  converting  to printable  characters.    It  also  includes the  dates  the
  133. Macintosh  file was  created  and last  modified,  and  some  extra flag  bits.
  134. MacBinary is the  most compact format for storing a  Macintosh file.   However,
  135. because MacBinary files retain binary data, they can be uploaded and downloaded
  136. only by programs which  use an 8-bit data path.   Usually,  such  a path is not
  137. available for VM/CMS  systems.   Programs such as Kermit can  simulate an 8-bit
  138. path using  printable characters,   but only at  the expense  of a  much longer
  139. transfer time.   MacBinary files in CMS  usually are given filetypes containing
  140. "BIN".  They consist of fixed-length 128-byte records.
  141.  
  142. USAGE NOTES
  143.  
  144.   1) Although the filetype of the input file will usually indicate which format
  145.      it  is  in,   BINHEX  determines  the   file's  format  by  examining  its
  146.      characteristics.   If the file has  fixed-length 128-byte records,  BINHEX
  147.      assumes MacBinary format.  Otherwise, BINHEX assumes BinHex format.
  148.  
  149.   2) The data in a BinHex format file begins  with a line containing a colon in
  150.      column one,  and  ends with a line  having a colon as  the last character.
  151.      CMS BINHEX skips  any other lines in  the file.   However,  BinHex  on the
  152.      Macintosh only skips  the comment line "(This file must  be converted with
  153.      BinHex 4.0)".   Thus,  even when the Check function reports no errors,  it
  154.      may still  be necessary to  delete extraneous  lines from the  BinHex file
  155.      before BinHex on the Macintosh will accept the file.
  156.  
  157.   3) BinHex  format  files do  not  contain  all  the information  included  in
  158.      MacBinary files.  In particular, the creation and last modified dates, and
  159.      some flag bits are not stored.  As a result, this information is lost when
  160.      the COnvert function is used to convert from MacBinary to BinHex format.
  161.  
  162.   4) BINHEX cannot  detect if  the input  file is  not in  either MacBinary  or
  163.      BinHex format.   In this case,  BINHEX will  usually assume the file is in
  164.      BinHex format,  and give an "unexpected end-of-file" message when it fails
  165.      to find the first line of BinHex data.
  166.  
  167.   5) For a BinHex file, the maximum line length BINHEX can process is 256.
  168.  
  169. RESPONSES
  170.  
  171. 'fn ft fm': No errors detected.
  172.  
  173.           This is the normal response from  the Check function.   This response
  174.           is omitted when BINHEX is called from a CMS command,  or from an exec
  175.           file with "address COMMAND" in effect.
  176.  
  177. File: 'STARS16 HQX T1'  Format: BinHex
  178. Filename: 'Stars 1.6'
  179. Type: 'DFIL'  Creator: 'DMOV'  Flags: none
  180. Data fork size: 0; Resource fork size: 6,054
  181. Character count: 10,140.
  182.  
  183.           This is  the response from  the Describe  function for a  BinHex file
  184.           when the  Rate option is  not used.    This is the  shortest possible
  185.           description.
  186.  
  187. File: 'TERM412 BIN M1'  Format: MacBinary
  188. Filename: 'Term 4.12'
  189. Type: 'APPL'  Creator: 'TRMA'  Flags: Bndl+Init
  190. Data fork size: 0; Resource fork size: 52,947
  191.       Created: Thu, May 28, 1987  2:01:25 AM
  192. Last Modified: Thu, May 28, 1987  2:02:04 AM
  193. Character count: 53,120 (4 minutes, 55 seconds at 180 cps).
  194.  
  195.           This is the response from the  Describe function for a MacBinary file
  196.           when  the  Rate  option  is used.    This  is  the  longest  possible
  197.           description.
  198.  
  199. OTHER MESSAGES AND RETURN CODES
  200.  
  201.      DMSBIN631E 'STEM' option is only available from an EXEC2 or REXX exec.
  202.                 RC=4
  203.      DMSBIN001E Error in command after 'token'.  RC=24
  204.      DMSBIN002I Issue BINHEX ? or HELP CMS BINHEX for more information.
  205.      DMSBIN003E Invalid option 'xxxxxxxx'.  RC=24
  206.      DMSBIN010E Invalid rate 'xxxxxxxx'.  RC=24
  207.      DMSBIN048E Invalid mode 'xxxxxxxx'.  RC=24
  208.      DMSBIN637E Missing value for the 'STEM' option.  RC=24
  209.      DMSBIN002E File 'fn ft fm' not found.  RC=28
  210.      DMSBIN024E File 'fn ft fm' already exists.  RC=28
  211.      DMSBIN044E Record length exceeds allowable maximum.  RC=32
  212.      DMSBIN005E Invalid character 'x' in 'fn ft fm' at line mmmmmm position
  213.                 nnn.  RC=36
  214.      DMSBIN006E Unexpected end-of-file reading 'fn ft fm'.  RC=36
  215.      DMSBIN037E Disk 'mode' is read-only.  RC=36
  216.      DMSBIN069E Disk 'mode' not accessed.  RC=36
  217.      DMSBIN007E 'fn ft fm': CRC error for BinHex header.  RC=44
  218.      DMSBIN008E 'fn ft fm': CRC error for BinHex data fork.  RC=44
  219.      DMSBIN009E 'fn ft fm': CRC error for BinHex resource fork.  RC=44
  220.      DMSBIN104S Error 'nn' reading file 'fn ft fm' from disk.  RC=1nn
  221.      DMSBIN105S Error 'nn' writing file 'fn ft fm' on disk.  RC=1nn
  222.      DMSBIN632E Error setting EXEC variable: RC=nnnnn from 'EXECCOMM'.  RC=200
  223.  
  224. .cs 3 off
  225.